home *** CD-ROM | disk | FTP | other *** search
/ Aminet 37 / Aminet 37 (2000)(Schatztruhe)[!][Jun 2000].iso / Aminet / dev / misc / MuLink.lha / MuLink / MuTools / MuLink.readme < prev    next >
Text File  |  1999-11-14  |  10KB  |  257 lines
  1. MuLink
  2. _____________________________________________________________________________
  3.  
  4. Purpose of MuLink:
  5.  
  6. MuLink is a linker for post-processing final executable binaries. It will
  7. write-protect selected hunks - by default the CODE segment - of the binary,
  8. and will hence protect them from getting modified or overwritten by faulty
  9. code. Hence, MuLink'd programs will benefit from a feature native to most
  10. operating systems but AmigaOs - protection of executable code.
  11.  
  12. Needless to say that programs that use self-modifying code cannot be MuLink'd,
  13. more about the caveats below.
  14.  
  15. MuLink is mainly a developer tool that should be run on a file as soon as it
  16. is out of the debugging stage and runs clean. MuLink'd programs cannot be
  17. debugged with a standard monitor (e.g. MonAm) because breakpoints can't be
  18. set in the - then writeprotected - code. See below for how to write a 
  19. debugger without this shortcoming.
  20.  
  21. MuLink'd programs use the "OVERLAY" mechanism of the AmigaOs. This means
  22. that part of the code is no longer read by the default AmigaOs loader,
  23. LoadSeg() namely. This has good and bad side effects. The bad is that most
  24. programs operating on executable files will not be able to process it,
  25. including "Hunk" for example. Additionally, some virus scanners might 
  26. indicate failures because they do not implement overlay scanning correctly.
  27. The good is that this effect might be desired for commercial programs, 
  28. and that virii will, too, most likely not be able to infect the program. 
  29. An infected overlayed program will most likely not work at all. After all,
  30. you should keep an un-MuLink'd version of the program private, and should
  31. publish the MuLink'd version.
  32.  
  33. _____________________________________________________________________________
  34.  
  35. Synopsis:
  36.  
  37. MuLink OVLYMGR/K,FROM=ROOT/A,TO/A,HUNKS/K,BUFSIZE/N,VERBOSE/S: 
  38.  
  39.  
  40. OVYLMGR:        The file name of the overlay manager, i.e. the
  41.             part of the file that replaces the AmigaOs loader.
  42.             This part will be linked to the beginning of your
  43.             binary. By default, this is 
  44.  
  45.             MMU:MuOVLYMGR
  46.  
  47.             and there's little reason to use a different
  48.             overlay manager.
  49.             It's actually that little file that does all the
  50.             MMU magic for you, using the mmu.library of course.
  51.  
  52. FROM=ROOT:        The file to be MuLink'd. This MUST be a final
  53.             executable, no object modules are allowed here.            
  54.             All debugging information will be stripped from this
  55.             file; furthermore, overlays are not allowed here
  56.             because the extended loader - the MuOVLYMGR - is
  57.             not yet able to process them. This might change in
  58.             the future.
  59.  
  60. TO:            The final output file. This will be an executable,
  61.             again. MUST be different from the root file or
  62.             strange and wonderful things may happen.
  63.  
  64. HUNKS:            Defines which hunks should be write-protected. By
  65.             default, all CODE hunks - and only these hunks -
  66.             get write protected. 
  67.     
  68.             This option is given by a comma-separated list
  69.             of an exclude/include indicator and a hunk 
  70.             specification:
  71.  
  72.             o) A plus or a minus sign, specifying whether the
  73.                specified hunk should be included or excluded
  74.                from the protection. 
  75.  
  76.             o) A hunk specification. This is either one of
  77.                the following strings, or the number of the hunk
  78.                as decimal string, counting from zero for the 
  79.                first hunk:
  80.  
  81.             CODE        all code hunks
  82.             DATA        all data hunks
  83.             BSS        all blank space segment hunks
  84.             CODE_C        all code hunks that are to be
  85.                     loaded into CHIP memory (rare!)
  86.             DATA_C        all data hunks to be loaded into
  87.                     CHIP memory
  88.             BSS_C        all bss hunks for CHIP memory
  89.             CODE_F        all code hunks to be loaded into
  90.                     FAST memory
  91.             DATA_F        data hunks for FAST memory
  92.             BSS_F        BSS hunks for FAST memory
  93.  
  94.             The list is processed item by item, hence latter
  95.             items of the list override former ones. For example,
  96.             
  97.             HUNK="+CODE,-DATA,-BSS"
  98.  
  99.             would be the build-in default, whereas
  100.  
  101.             HUNK="+CODE,+DATA,-BSS,-DATA_C"
  102.  
  103.             would protect all code and data hunks except those    
  104.             data hunks that contain CHIP memory data. 
  105.  
  106.             As a side remark you should note that the MMU - and
  107.             hence MuLink - will not be able to protect data from
  108.             write access by the blitter anyhow. 
  109.  
  110.  
  111. BUFSIZE/N:        Defines the size of the I/O buffers used by MuLink.
  112.             This defaults to 4K (4096) and should be something
  113.             between 256 bytes and 32K. There's rarely need to
  114.             adjust this since the I/O routines used by MuLink are
  115.             pretty fast anyhow.
  116.  
  117. VERBOSE/S:         Turns on additional debug information that gets
  118.             printed onto the output console.
  119.  
  120. _____________________________________________________________________________
  121.  
  122. Special caveats of MuLink:
  123.  
  124.  
  125. - The final binary will REQUIRE the mmu.library. It will hence NOT run on
  126. P5 boards using the (original) ppc.library. This library is obsolete anyhow
  127. and not supported. The binary will request and open the mmu.library and will
  128. refuse to load in case the library is not available.
  129.  
  130. - It makes usually no sense to protect the data or bss segments, even though
  131. this might work in some cases. Some compilers will produce only DATA segments
  132. instead of DATA and BSS segments, reserving BSS space in the DATA segment.
  133.  
  134. For optimal performance, you should configure your compiler either to place
  135. constant strings in one separate hunk, or to merge them with the CODE hunk
  136. so to allow MuLink to protect them apart from the remaining (alterable) data.
  137.  
  138. - MuLink will not be able to protect overlayed segments. This is a 
  139. shortcoming of the current loader MuOVLYMGR.
  140.  
  141. - MuLink'd programs are NO LONGER pure. This is because the loader is
  142. REQUIRED to enable and disable protection. Besides that, protecting tiny
  143. programs - as most pure programs are - will waste a lot of memory because
  144. the loader has to round the hunk start addresses to page boundaries.
  145.  
  146. - MuLink will usually not work on "run-back and stay-resident" programs
  147. because most of these programs will attempt to modify their code hunk to
  148. build a faked segment list. A modified loader might allow that in future.
  149.  
  150. - The loader will choose one of the the two available MMU protection modes,
  151. depending on whether "MuForce" is running in your system. In case it is not,
  152. "defensive" MAPP_ROM protection is used. This means that write accesses will
  153. be silently ignored, even though they will not modify the code at all. If
  154. "MuForce" is active, though, it will choose "aggressive" MAPP_WRITEPROTECTED
  155. protection, causing a "MuForce hit". This will help you debugging your 
  156. software.
  157.  
  158. - MuLink'd programs will only write protect the code for user mode accesses.
  159. Supervisor mode write accesses remain valid. This means that a debugger
  160. should switch to supervisor mode before setting a break point into the code,
  161. then flush the cache line and then return to user mode. 
  162.  
  163. _____________________________________________________________________________
  164.  
  165. Internal information for the experts - how a MuLink'd program looks like:
  166.  
  167.  
  168. HUNK_HEADER    of the loader.
  169.  
  170. HUNK_CODE    The loader. 
  171.     This is a standard AmigaOs binary. However, the HUNK_HEADER does not
  172.     indicate a overlayed program. First because it was easier to do so,
  173.     second to fake some virus protection software, and third to avoid
  174.     memory waste and to keep the overlay hunk table as small as possible.
  175.     The DOS "Majik Word" $ABCD is, however, as usual in the second long
  176.     word of the binary. Besides that, there is no identifier as the 
  177.     overlay manager = the loader is a custom loader.
  178.  
  179. HUNK_OVERLAY    The overlay node: All entries are longs 
  180.  
  181.     HUNK_OVERLAY        0x000003f5
  182.     size-1            size of the overlay data in longs, minus one.
  183.     fileofs            file offset from the beginning of the file
  184.                 to the offset where the first HUNK_CODE of
  185.                 the main program starts. NOT to its 
  186.                 HUNK_HEADER, though!
  187.     ovlsize            size of the loader segment in long words.
  188.                 This is required, too, because the loader
  189.                 write-protects itself after having done its
  190.                 job.
  191.     loaderofs        byte offset of the loader into its module
  192.     loadermodule        module in which the loader is put for
  193.                 protection.
  194.  
  195. A "module" is a common memory space for hunks sharing the same memory and
  196. protection requirements. Unlike the Os loader, the MuOVLYMGR does not allocate
  197. the memory for the hunks individually, but in blocks called "modules". This
  198. was done mainly to reduce the memory waste due to round-off problems when
  199. rounding to MMU page boundaries. Hence, if hunk 0 and 3 are code hunks and to
  200. be protected, both will end up in one module. The loader will mimik the
  201. standard BCPL segment linkage for the file though, so this "module" technique
  202. is transparent to the file and will not cause compatibility problems.
  203. Especially, the loader code is always put into a "protected" module.
  204.  
  205.     num_modules        the number of modules for the file
  206.  
  207.     For each module:
  208.  
  209.         module_id    a unique module identifier, counted from
  210.                 zero up. Currently not needed by the loader.
  211.  
  212.         memory_attrs    memory attributes passed to AllocMem() on
  213.                 allocation of the module. Reflects the
  214.                 flags in the HUNK_HEADER of the source.
  215.  
  216.         properties    memory properties to be passed to the MMU
  217.                 library. Currently, only one bit is 
  218.                 recognized, MAPP_ROM, namely, to enable the
  219.                 protection. The loader will modify this to
  220.                 MAPP_WRITEPROTECTED in case it finds
  221.                 "MuForce" active.
  222.  
  223.         length        length of the module, again in LONG WORDS.
  224.  
  225.     
  226.     num_hunks        the number of hunks in the source executable.
  227.         
  228.     For each hunk:
  229.  
  230.         hunk_type    type of the hunk, i.e. HUNK_CODE,HUNK_DATA or
  231.                 HUNK_BSS. Currently ignored by the loader.
  232.  
  233.         hunkofs        byte offset of the hunk from the beginning 
  234.                 of its module.
  235.  
  236.         hunksize    size of the hunk in LONG WORDS, including
  237.                 the memory attributes. The memory attributes
  238.                 are, however, currently ignored.
  239.  
  240.         hunkmodule    module the hunk is placed in, counting from
  241.                 zero.
  242.  
  243.  
  244. HUNK_HEADER    The HUNK_HEADER of the main file. This is here to allow
  245.         easier unlinking, if required, but this part is completely
  246.         ignored by the loader.
  247.  
  248. HUNK_CODE    The first code hunk of the main binary. The "fileofs" entry
  249.         above points to this identifier.
  250.  
  251. Below that:    The usual executable hunk structure as for all other loadable 
  252.         binaries.
  253. _____________________________________________________________________________
  254.  
  255. So long,
  256.         Thomas Richter (June 1999)
  257.